What will we talk about today?

1. Components of an R Markdown document
2. Output options
3. Content
4. Formatting
5. Trouble-shooting

General tips

• Treat your data as read-only
• Comment code early and often
• Keep code chunks small
• Label chunks to help with diagnosing issues
• Nest all files under one directory (if possible)

YAML header

• The first part of your document is called the YAML header
• This is where you set global options for the output type and formatting
• This header is set apart from the rest of the document by three dashes

---
title: "Why R Markdown Is the Best"
author: "Me"
output: html_document
---

Markdown

Plain text-formatting allows for conversion to different document types

1. People
1. Order
1. Our
1. Patties

1. People
2. Order
3. Our
4. Patties

Code chunks

• Code chunks are set apart from markdown by three backticks at the beginning and end
• In curly brackets after the first set of backticks, you specify the coding language you want to use
• You can also add other arguments in the curly brackets

```{r example}
## Load packages ##

# Package list
pkg_list <- c(tidyverse", "ggplot2", "kableExtra", "patchwork")

# Load packages
pacman::p_load(pkg_list, character.only = TRUE)
```

Code chunks (continued)

To test your code chunks, you can:

• Highlight the relevant lines of code and hit CTRL/command + enter
• Hit the green play button in the upper right-hand corner of the chunk
• Use the Run dropdown menu at the top right of the document

Output types

• HTML: most flexible
• PDF: requires \(\LaTeX\) to compile (TinyTeX distribution)
• Microsoft Office (Word/Powerpoint): most convenient for collaboration

YAML specification

• Use the output argument in the YAML header
• Pay attention to indentation and colons
• Press the knit button or command/CTRL + shift + K

Render

• Render files in the console with rmarkdown::render(file, output_format)
• Create PDF from HTML with pagedown::chrome_print(file)

Built-in templates

• Documents
  • html_document
  • pdf_document
  • word_document
• Presentations
  • ioslides_presentation and slidy_presentation for HTML
  • beamer_presentation for PDF
  • powerpoint_presentation
• Interactive Shiny documents and presentations

R package templates

• Presentations: revealjs
• CVs: vitae
• Academic posters: posterdown
• APA-formatted articles: papaja
• Journal templates: rticles
• HTML theme: prettydoc
• Manuscripts: single document output from bookdown

\(\LaTeX\) templates

---
output:
  pdf_document:
    template: plos_latex_template.tex
---

Word document templates

Go to the Styles Pane in Word, format, and “Update to Match Selection”

---
output:
  word_document:
    reference_docx: template.docx
---

Markdown

• Look at R Markdown: The Definitive Guide for a comprehensive list of type-setting features
• Line spacing matters
• Escape special characters with a backslash

Inline R

# Pull species column from iris and get unique values in column
species <- iris %>% pull(Species) %>% unique()

# Get number of unique species
species_count <- length(species)

• I can report that there are 3 species without writing out the number itself with `r species_count`
• I can also reference report the exact species names with`r species`: setosa, versicolor, virginica

YAML parameters

General YAML parameters

---
title: |
  <center> A very impressive title: </center>
  <center> An equally impressive subtitle </center>
---

YAML references

• Bibliography: .bib (I use BibDesk for my reference manager)
• Citation style language: .csl
• \(\LaTeX\) styling: .cls
• HTML styling: .css
• Interacting with pandoc: .lua (multiple bibliographies)

Inline \(\LaTeX\)  and CSS code

• \(\LaTeX\) with PDFs
  • Calling \(\LaTeX\) packages
  • Using symbols
  • Using type-setting commands (e.g., \vspace{12pt})
• CSS with HTML

Editing templates

1. Find out where your R packages “live” by calling installed.packages()
2. If the template generates a style document (e.g., .cls) in the directory with your .Rmd file, you can edit that without going to the package

Custom functions

• You can write R formatting functions for yourself to make your life easier when you’re referencing variables in your text (e.g., p values)
• You can find all of my convenience functions in the source script in my reproducible scientific manuscripts template

Identifying issues

1. Warnings vs. errors
2. RStudio vs. R Markdown environments
3. Package issues
4. Strategies for troubleshooting issues

Warning

Chunk error

Markdown/YAML error

Environments

R code and environments

# Define new variable y
y <- 100

# When I run this chunk, I get the expected output (150),
# but it fails when I try to knit the document
# I've set eval=FALSE for this chunk, so it doesn't try to run and prevent my document from knitting
print(x + y)

Package specification

• Different packages can have the same name for different functions, creating a name-space conflict
• Tell R which package to look in with package::function notation

Updates

• Update your TeX distribution from the command line
• Update all packages (including rmarkdown) in your library with update.packages(path)
• Update individual packages with install.packages("package")
• Update R in the console with the updateR package
• Re-download RStudio to update

Reset your R environment

• Clear all variables by running rm(ls = list()) in the console
• Restart your R environment with CTRL/(control + fn) + shift + F10
• Run all chunks individually in order before compiling to test code

Search for information

• Use the Help window in RStudio
• Search for the package in the console with ?package or ??package
• Google the error you’re getting with the package or function you’re trying to use

Reference documents

• Official R Markdown Guide
• My R Markdown Guide
• R Markdown Cheat Sheet
• R Markdown Reference Guide
• Keyboard shortcuts
• knitr documentation

Other packages/tools

• Sublime Text text editor
• scholar package for automatically downloading citations from Google Scholar
• devtools package for installing packages/plug-ins from GitHub (e.g., papaja)
• wordcountaddin plug-in for checking word count and readability

Questions?